How To Design A Good API and Why it Matters 笔记

Categories: Java; Tagged with: Google • Java • Joshua Bloch; @ June 2nd, 2013 23:22

YouTube: http://www.youtube.com/watch?v=aAb7hSCtvGw

by Joshua Bloch (Principal Software Engineer of Google)

API设计是重要的

对公司来说, API 很可能成为公司重要财产, 客户要购买, 学习, 停止使用API的代价过高, 并且, 成功的API可以帮助公司抓牢客户. 当然, 设计太烂的API也会拖垮公司.

对于程序员来说, 如果你写程序, 那你就是一个API设计师, 有用的模块会被重用, 但一旦被其他人使用, 那就不能随便更改. 如果在平时的编程当成设计API会提高代码质量

干货来了:

Characteristics of a Good API

• Easy to learn
• Easy to use, even without documentation 多美好啊
• Hard to misuse
• Easy to read and maintain code that uses it
• Sufficiently powerful to satisfy requirements
• Easy to extend
• Appropriate to audience

Outline

I. The Process of API Design

1. Gather Requirements – With a Healthy Degree of Scepticism

我们经常会收到解决方案而不是需求 — 所以我们常说, Product management/BA们不要提Solution.

我们的工作是提炼需求, 最好是以Use Case的形式.

(以前我有个Technical Manager, 他总是要求我们吃透需求, 挑战PM. 事实上, 如果暂时妥协, 接受未经挑战的需求, 可能会为日后的重构埋下伏笔)

Can be easier and more rewarding to build something more general

2. Start with Short Spec–1 Page is Ideal

跟领导演讲稿一样

“If you want me to speak for an hour – give me a moment’s notice; if you want me to speak for half an hour, give me a day’s notice; if you want me to speak for five minutes—give me a week.”__Winston Churchill

3. Write to Your API Early and Often

Code lives on as examples, unit tests

II. General Principles

API Should Be As Small As Possible But No Smaller

API should satisfy its requirements

When in doubt leave it out
_ Functionality, classes, methods, parameters, etc.
_ You can always add, but you can never remove

Minimize Accessibility of Everything

Names Matter–API is a Little Language

Document Religiously
• Document every class, interface, method,
constructor, parameter, and exception
_ Class: what an instance represents
_ Method: contract between method and its client
_ Preconditions, postconditions, side-effects
_ Parameter: indicate units, form, ownership
• Document state space very carefully

III. Class Design

Minimize Mutability

Classes should be immutable unless there’s a
good reason to do otherwise
_ Advantages: simple, thread-safe, reusable
_ Disadvantage: separate object for each value
• If mutable, keep state-space small, well-defined
_ Make clear when it’s legal to call which method

Subclass Only Where It Makes Sense

Design and Document for Inheritance or Else Prohibit it

Inheritance violates encapsulation (Snyder, ‘86)

IV. Method Design

Don’t Make the Client Do Anything the Module Could Do

Don’t Violate the Principle of Least Astonishment

User of API should not be surprised by behavior

Fail Fast–Report Errors as Soon as Possible After They Occur

快速失败

Provide Programmatic Access to All Data Available in String Form

Overload With Care

Avoid ambiguous overloadings, If you must provide ambiguous overloadings, ensure same behavior for same arguments.

Just because you can doesn’t mean you should: often better to use a different name

Use Appropriate Parameter and Return Types

• Favor interface types over classes for input
_ Provides flexibility, performance
• Use most specific possible input parameter type
_ Moves error from runtime to compile time
• Don’t use string if a better type exists
_ Strings are cumbersome, error-prone, and slow
• Don’t use floating point for monetary values
_ Binary floating point causes inexact results!
• Use double (64 bits) rather than float (32 bits)
_ Precision loss is real, performance loss negligible

Use Consistent Parameter Ordering Across Methods

Avoid Long Parameter Lists

V. Exception Design

VI. Refactoring API Designs

Links:

Rule of three

The New Google Maps 新版Google地图 <-> <<季羡林谈人生>> 笔记